---
title: SQL Agent
---

This example shows how to build a text-to-SQL system that:
1. Uses Agentic RAG to search for table metadata, sample queries and rules for writing better SQL queries.
2. Uses dynamic few-shot examples and rules to improve query construction.
3. Provides an interactive Streamlit UI for users to query the database.

We'll use the F1 dataset as an example, but you can easily extend it to other datasets.

### Key capabilities
- Natural language to SQL conversion
- Retrieve table metadata, sample queries and rules using Agentic RAG
- Better query construction with the help of dynamic few-shot examples and rules
- Interactive Streamlit UI

<video
  autoPlay
  muted
  controls
  className="w-full aspect-video"
  src="/videos/sql_agent.mp4"
></video>

### Simple queries to try
- "Who are the top 5 drivers with the most race wins?"
- "Compare Mercedes vs Ferrari performance in constructors championships"
- "Show me the progression of fastest lap times at Monza"
- "Which drivers have won championships with multiple teams?"
- "What tracks have hosted the most races?"
- "Show me Lewis Hamilton's win percentage by season"

### Advanced queries with table joins
- "How many races did the championship winners win each year?"
- "Compare the number of race wins vs championship positions for constructors in 2019"
- "Show me Lewis Hamilton's race wins and championship positions by year"
- "Which drivers have both won races and set fastest laps at Monaco?"
- "Show me Ferrari's race wins and constructor championship positions from 2015-2020"

## Code

The complete code is available in the [Agno repository](https://github.com/agno-agi/agno).

## Usage

<Steps>
  <Step title="Clone the repository">
    ```bash
    git clone https://github.com/agno-agi/agno.git
    cd agno
    ```
  </Step>

  <Step title="Create virtual environment">
    ```bash
    python3 -m venv .venv
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash
    pip install -r cookbook/examples/streamlit_apps/sql_agent/requirements.txt
    ```
  </Step>

  <Step title="Run PgVector">
    First, install [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/).

    Then run either using the helper script:
    ```bash
    ./cookbook/scripts/run_pgvector.sh
    ```

    Or directly with Docker:
    ```bash
    docker run -d \
      -e POSTGRES_DB=ai \
      -e POSTGRES_USER=ai \
      -e POSTGRES_PASSWORD=ai \
      -e PGDATA=/var/lib/postgresql/data/pgdata \
      -v pgvolume:/var/lib/postgresql/data \
      -p 5532:5432 \
      --name pgvector \
      agnohq/pgvector:16
    ```
  </Step>

  <Step title="Load F1 data">
    ```bash
    python cookbook/examples/streamlit_apps/sql_agent/load_f1_data.py
    ```
  </Step>

  <Step title="Load knowledge base">
    The knowledge base contains table metadata, rules and sample queries that help the Agent generate better responses.

    ```bash
    python cookbook/examples/streamlit_apps/sql_agent/load_knowledge.py
    ```

    Pro tips for enhancing the knowledge base:
    - Add `table_rules` and `column_rules` to guide the Agent on query formats
    - Add sample queries to `cookbook/examples/apps/sql_agent/knowledge_base/sample_queries.sql`
  </Step>

  <Step title="Set up API keys">
    ```bash
    # Required
    export OPENAI_API_KEY=***

    # Optional
    export ANTHROPIC_API_KEY=***
    export GOOGLE_API_KEY=***
    export GROQ_API_KEY=***
    ```
    We recommend using gpt-5-mini for optimal performance.
  </Step>

  <Step title="Launch the app">
    ```bash
    streamlit run cookbook/examples/streamlit_apps/sql_agent/app.py
    ```
    Open localhost:8501 to start using the SQL Agent.
  </Step>
</Steps>

Need help? Join our [Discourse community](https://community.agno.com) for support!
